home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 33 / Amiga Format AFCD33 (Issue 117, Dec 1998).iso / +system+ / tools / workbench / -archivers- / ppcxdms / xdms.txt < prev    next >
Text File  |  1998-09-07  |  14KB  |  335 lines
  1.  
  2.  
  3.     xDMS  version 1.1    Released in 18-Feb-98
  4.  
  5.  
  6. Introduction:
  7. -------------
  8.  
  9.     Some time ago I started using UAE and Fellow Amiga emulators in the PC,
  10. while  still  using  my Amiga.  Both emulators are very nice, and I started
  11. testing  some  of my old games and demos on it.  But a thing annoyed me.  I
  12. have  a  number of CDs with demos and other software, with hundreds of disk
  13. images  compressed  with DMS.  DMS was always the Amiga 'de facto' standard
  14. for  storing copies of non-dos disks, as used by most games and demos.  But
  15. the  emulators required the Amiga software to be in uncompressed disk image
  16. format  (now  known as .ADF) or disk images compressed with gzip (ADZ).  To
  17. use  my  DMS  archives  in  the emulators I had to uncompress them with DMS
  18. inside  the  emulation,  saving  it as an uncompressed disk image in the PC
  19. hard  disk.   It  was  very  boring, and also a waste of time and hard disk
  20. space,  since  I  could  not  leave the files in the CDs.  I thought a much
  21. better  solution  would  be  to  add  direct  support  for DMS files in the
  22. emulators itselves, in the same way as they support gzip compressed images.
  23. But  as  DMS  uses  a proprietary format, I thought DMS support in the near
  24. future would be unlikely.  So I decided to do something myself and began to
  25. study  the  inner workings of DMS.  After some days of hard work, I wrote a
  26. portable  DMS  unpacker,  xDMS.   xDMS  is  more  useful for users of Amiga
  27. emulators, but can also be useful for actual Amiga users too.  In fact, the
  28. extract command of xDMS can be very useful to actual Amiga users, just need
  29. an update of readdisk.
  30.  
  31.  
  32.  
  33. xDMS Features:
  34. --------------
  35.  
  36.   Supports   decompression   of   files  compressed  using  all  known  DMS
  37. compression  modes,  including  old  and  obsolete ones, and also encrypted
  38. files, for 100% compatibility.
  39.   Can  test  DMS  files integrity, view file informations and show attached
  40. Banners and FILEID.DIZ .
  41.   Can generate standard disk images and compressed disk images, using gzip,
  42. if you want to store your files in ADF or ADZ formats.
  43.   Can  extract  the  files  contained  inside  the  DMS  archives,  if  the
  44. compressed disk is an AmigaDOS disk, using readdisk made by Bernd Schmidt.
  45.   Can  process  multiple files in batch with a single command, and also use
  46. stdin and stdout for input and output of data.
  47.  
  48.  
  49.  
  50. Instalation:
  51. ------------
  52.  
  53.   xDMS  was  written  in  ANSI  C  and  should work with most ANSI C or C++
  54. compilers  and  platforms  with  minor  or no changes.  It was tested under
  55. Linux  with  GCC,  MS-DOS  with DJGPP and Amiga with SAS/C and worked well,
  56. 0without  warnings.   To compile it with GCC or DJGPP you can just use make
  57. with  the supplied Makefile.  For other compilers you may have to modify it
  58. slightly.   A  smakefile  for  SAS/C  is also supplied.  After a successful
  59. compilation  you  can  install  the  generated executable somewhere in your
  60. path.  You also need to install gzip and readdisk if you want to be able to
  61. create  gzip  compressed  disk  images and extract files from DMS.  gzip is
  62. available  in  most public domain software libraries.  Readdisk is supplied
  63. with  UAE.   You  probably  already  have  both.  Also, as I'm sendind this
  64. program  to  UAE  and  Fellow authors and allowing them (or anyone else) to
  65. include  it with their programs and change it in any way, perhaps xDMS just
  66. came  together  with  your emulator, and was installed with it and directly
  67. supported.  In this case you have nothing to worry.
  68.  
  69.  
  70.  
  71. Usage:
  72. ------
  73.  
  74.   xDMS  is  a  shell  utility program.  When executed without arguments, it
  75. shows an usage screen.  The template of xDMS is the following:
  76.  
  77.     xdms [options] <command> {<dms_file[.dms]> [+output]}
  78.  
  79. Arguments inside [] are optional. Arguments inside <> are required.
  80. Arguments inside {} can be used one or several times.
  81.  
  82. A command is indicated by a letter and can be one of the following:
  83.  
  84.      t : Test DMS archives
  85.      u : Unpack DMS archives to disk images
  86.      z : Unpack to disk images and compress it with gzip
  87.      x : Extract files inside DMS archives using readdisk
  88.      v : View DMS archives information
  89.      f : View full information
  90.      d : Show attached FILEID.DIZ
  91.      b : Show attached Banner
  92.  
  93.  
  94.   If  the  supplied  input  DMS  file  name  doesn't  have  a  .DMS or .dms
  95. extension, a default .dms will be appended to it.
  96.   The  output argument is optional and specifies a file name or a directory
  97. for  each  unpacked  file.   If  the output filename is not supplied, it is
  98. generated  from  the  input  filename.  If the generated file is a standard
  99. disk  image  it  will have the .adf extension.  If it is a compressed image
  100. the  extension  will  be  .adz  .   If  you  supply an output file name, no
  101. extension  will  be  added.   By default, files are unpacked to the current
  102. directory,  unless  you specify another directory with the output file name
  103. or use the -d option.
  104.   Commands  z  and  x  respectively  need gzip and readdisk instaled in the
  105. current path, or it will fail.
  106.   When  extracting files with x option, xDMS will call readdisk and it will
  107. reconstruct  the  tree  of  files  and directories contained inside the DMS
  108. compressed  disk  image,  starting in a directory with the same name as the
  109. volume  name  of  the  disk in the DMS file.  This command can fail if xDMS
  110. can't  execute  readdisk,  or if the dms compressed disk is not an AmigaDOS
  111. disk.  The current version of readdisk supplied with UAE 0.69 only supports
  112. old  OFS Kickstart 1.x compatible disks, reporting any of the newer formats
  113. introduced  with AmigaOS 2.0 or newer as non-dos disks, while they actually
  114. are.
  115.   The  v  commands  show  some  information  contained in DMS files, as the
  116. version  of  DMS  that  created it, the type of the disk, date of creation,
  117. number  of  tracks,  etc.   The  f  command  also  shows  additional tracks
  118. informations.
  119.   The  b command shows the banner, if the file contains one.  A banner is a
  120. text  that  is  displayed  when  DMS  unpacks  a  file and usually contains
  121. informations about the group/BBS/person that made it.
  122.   The  f  command  shows the FILEID.DIZ, if found in the DMS.  It is a text
  123. that identifies what the DMS file contains.
  124.   You can also supply as input filename stdin and/or +stdout as output.  in
  125. this case xDMS will read the data from the standard input and/or send it to
  126. the standard output.
  127.   You  can  supply  multiple  input  and optional output files and use wild
  128. cards.   When  using  wildcards,  the +output argument will affect only the
  129. last  file name expanded from the wildcard.  To supply a global destination
  130. directory  you  must  use  the -d option.  All commands and options are not
  131. case sensitive.
  132.  
  133. You can also supply one or more (or none) of the following options:
  134.  
  135.     -q : Quiet
  136.     -v : Verbose
  137.     -d <destdir>  : Set destination directory
  138.     -p <password> : Decrypt encrypted archives using password
  139.  
  140.  
  141.   When  more than one option is supplied they must be separated.  You can't
  142. use something like -qd dir .
  143.   The  quiet  option  suppresses  all  messages  usually  emited  by  xDMS,
  144. including error messages.  It is mostly to be used when xDMS is called from
  145. inside  emulators  or  some type of front-end.  The program that calls xDMS
  146. can  verify  if  the  operation  was successful checking the return code of
  147. xDMS.   It  will be 0 if the operation was successful or not 0 if it failed
  148. for one or more files.
  149.   The verbose option makes xDMS display more messages than it usually does,
  150. including  a  progress  indicator  when unpacking files.  This indicator is
  151. only useful if you have a very slow computer.
  152.   The  -d  option specifies a global destination directory.  This directory
  153. name  is  added  before  the  name  of  any output file or output directory
  154. supplied with +output in the command line.
  155.   The  -p  option  uses  a  password  to  decrypt the dms files if they are
  156. encrypted.   DMS uses a very lame encryption algorithm that could be easyly
  157. cracked.  In fact, if the file is encrypted, and contains a banner, you can
  158. unpack it with any password.
  159.  
  160.  
  161. Some examples:
  162.  
  163.     xdms u foo.dms
  164.  
  165. This  will  unpack the file foo.dms in the current directory and save it as
  166. foo.adf, also in the current directory.
  167.  
  168.  
  169.     xdms -v -d /tmp/tst u foo +bar.dsk
  170.  
  171. This  will  unpack the file foo.dms in the current directory and save it as
  172. /tmp/tst/bar.dsk  .   Aditional  messages  and a progress indicator will be
  173. displayed.
  174.  
  175.     xdms f ram:Hardwired1.dms   (in the Amiga or inside Amiga emu)
  176.  
  177. This  will  show  informations about the file Hardwired1.dms in Amiga's Ram
  178. Disk, including tracks information.
  179.  
  180.     xdms -p treva u tst1 tst2 +tstdir/ttt tst3.DMS +stdout >tora
  181.  
  182. This  will (try to) unpack the files tst1.dms, tst2.dms and tst3.DMS in the
  183. current directory.  If any of them is encrypted xDMS will try to decrypt it
  184. using  the  password  "treva".   tst1.dms  will  be  unpacked  as tst1.adf,
  185. tst2.dms  as  tstdir/ttt  and  tst3.DMS  will be unpacked to stdout that is
  186. redirected to file tora.
  187.  
  188.     xdms -d /home/apele/uae/demos z /mnt/cdrom/*.dms       (under Unix)
  189.  
  190.     xdms -d c:\emul\fellow\demos z f:\*.dms              (under MS-DOS)
  191.  
  192. This  will unpack all files with the dms extension in the root directory of
  193. a  CDROM  disk,  pack it again using gzip and save it in another directory.
  194. The generated files will have the .adz extension.
  195.  
  196.  
  197.     xdms -q x tst
  198.  
  199. This  will  (try  to)  extract the files contained inside the tst.dms file.
  200. The  files  and  directories  will  be extracted to a directory with a name
  201. equal  to  the  volume  name  of  the  disk  contained in the dms file.  No
  202. messages will be displayed.
  203.  
  204.  
  205.     xdms -d stdout u *.dms >bigfile
  206.  
  207. This  will  unpack all the dms files in the current directory and save them
  208. all to a single file.
  209.  
  210.  
  211.     xdms -d /home u apele +apele/yourfile.adf trevor +trevor/yourfile.adf
  212.  
  213. This will unpack the file apele.dms in the current directory and save it as
  214. /home/apele/yourfile.adf  .   Will  also  unpack  the  file  trevor.dms  as
  215. /home/trevor/yourfile.adf .
  216.  
  217.  
  218.     cat tst.dms | xdms u stdin +stdout | strings | more
  219.  
  220. This  will display the ascii strings inside the unpacked dms file.  In this
  221. case, xDMS is used as a filter.
  222.  
  223.  
  224.  
  225.  
  226. Known problems:
  227. ---------------
  228.   If  you  try  to extract the files (using the x command) of a DMS archive
  229. that  contains  a  disk  in one of the disk formats introduced with AmigaOS
  230. version  2  or  newer, it will fail.  Also, if you try to extract the files
  231. under  MS-DOS  it will almost always fail.  It's not a problem in xDMS.  It
  232. is  a  problem  in  the  current  version of readdisk.  It only suports OFS
  233. disks.   Another  problem  of readdisk is that it fails when executed under
  234. MS-DOS  and  the  DMS  archive  contains files with names invalid to MS-DOS
  235. rules.   If  your  Amiga disk compressed in the DMS archive contains a file
  236. named as Amazing_Amiga.txt.info, it will fail.  It works under Unix.  Under
  237. MS-DOS  readdisk  also  changes  the  current  working  directory after its
  238. execution,  if  you specify an output directory to it.  This can cause some
  239. problems  too.   I was thinking about adding internal support to extraction
  240. of  files to xDMS, with support to all Amiga native filesystems, or write a
  241. replacement to readdisk, but now I think I will just wait for Bernd Schmidt
  242. or someone else to update readdisk.
  243.   xDMS  doesn't  perform  internal  expansion of wildcards, but expects the
  244. shell  (or the compiler) to do it.  It is the usual under unix.  But if you
  245. use  it in a system where the shell does not perform wildcard expansion and
  246. your  compiler  also  does  not generate code to perform it, then wildcards
  247. will not work.  This is the case, for example when using xDMS in the Amiga,
  248. under  the  standard  Amiga Shell, when compiled with SAS/C.  I think Amiga
  249. GCC  adds  wildcard expansion to the program it compiles.  The same applies
  250. to  xDMS compiled with compilers like TurboC under MS-DOS.  DJGPP for MSDOS
  251. generate code to expand wildcards.
  252.  
  253.  
  254.  
  255. Acknowledgements:
  256. -----------------
  257.  
  258. xDMS  uses  source code fragments or informations from the following public
  259. domain or freeware programs:
  260.  
  261. Unix  LHA  by Masaru Oki :  xDMS Heavy mode decrunch functions are based in
  262. lha  static  lzh  functions.   DMS used parts of LHA and LZHUF in the first
  263. place.
  264.  
  265. LZHUF  by Haruyasu Yoshizaki :  xDMS Deep mode decrunch functions are based
  266. in LZHUF.
  267.  
  268. testdms  by  Bjorn Stenberg :  I got some initial information about the DMS
  269. headers with testdms, and also the CRC calculation function.
  270.  
  271.  
  272. xDMS  also  calls,  if  available,  gzip  made  by  Jean-loup Gailly / Free
  273. Software    Foundation,    and    readdisk    made    by    Bernd   Schmidt
  274. <crux@pool.informatik.rwth-aachen.de>
  275.  
  276.  
  277.  
  278. Last comments:
  279. --------------
  280.   I hope you find xDMS useful, be you using it with an actual Amiga or with
  281. an  emulator  to  remember the golden days of the Amiga.  I wrote it mostly
  282. because  I  thought  it  would take ages for DMS support to be added in the
  283. Amiga emulators as its authors were busy with other issues.  I also thought
  284. nobody else would do it.  Later, when xDMS was almost ready, I discovered I
  285. was  completely wrong.  David Tritscher was doing the same thing I was, and
  286. released  a  portable DMS decruncher in Aminet called undms (also spread by
  287. some users as dms2adf).  I tried his program and it appears to work nicely.
  288. But xDMS has far more features ;)
  289.   Also,  xDMS should not be cofused with xdm, the XWindows Display Manager,
  290. or with some of type of database management software package.
  291.  
  292.  
  293.  
  294. Copyright:
  295. ----------
  296.  
  297.   xDMS is released as public domain software.  You can spread it, modify it
  298. and use it in any way you like.  You can do anything with it without asking
  299. me first.  But I would like to know if you do something cool with it.
  300.  
  301.  
  302.  
  303. How to contact the author:
  304. --------------------------
  305.  
  306.   If  you  have some problem, you can contact me by e-mail.  But first make
  307. sure  you have read all this documentation, to not waste my time with silly
  308. questions.   If you have found a bug in xDMS please contact me.  If the bug
  309. is in readdisk, contact Bernd Schmidt.
  310.  
  311.  
  312.  
  313.  
  314.                                     Andre' R. de la Rocha
  315.  
  316.                                     e-mail address : adlroc@usa.net
  317.  
  318.  
  319.  
  320.  
  321. History:
  322. --------
  323.  
  324. Version 1.0 :  17-Feb-98
  325.     First release
  326.  
  327. Version 1.1 :  18-Feb-98
  328.     Reading/writing  to  stdin/stdout  under  MS-DOS didn't work correctly.
  329.     Fixed.
  330.  
  331.  
  332.  
  333. ---------------------------------------------------------------------------
  334.  
  335.